Team Tool Configuration Guide

The team tool allows PicoClaw to orchestrate multiple agents to complete complex tasks using various strategies (Sequential, Parallel, DAG, and Evaluator-Optimizer). This guide explains how to configure permissions, limits, and behavior.

Configuration Location

Settings are located in config.json under tools.team.

Comprehensive Example

{
  "tools": {
    "team": {
      "enabled": true,
      "max_members": 5,
      "max_team_tokens": 100000,
      "max_evaluator_loops": 3,
      "max_timeout_minutes": 20,
      "max_context_runes": 8000,
      "disable_auto_reviewer": false,
      "reviewer_model": "gpt-4o-mini",
      "allowed_strategies": [
        "sequential",
        "parallel",
        "dag",
        "evaluator_optimizer"
      ],
      "allowed_models": [
        {
          "name": "gpt-4o",
          "tags": ["vision", "code", "reasoning"]
        },
        {
          "name": "claude-3-5-sonnet",
          "tags": ["coding", "precise"]
        }
      ]
    }
  }
}

Field Reference

Feature Highlights

1. Robust Parallelism

In Parallel mode, if some workers fail while others succeed, the tool returns Partial Success. Successful results are preserved, and failures are summarized separately so the coordinator can decide how to proceed.

2. Context Truncation

To prevent "Token Bombs," the tool automatically truncates long outputs when injecting them as dependencies/context for downstream workers. You can tune this via max_context_runes.

3. Dedicated QA Reviewer

The Auto-Reviewer automatically validates artifacts like code or documentation. By setting reviewer_model, you can perform this validation with a highly efficient model to save on latency and costs.

4. DAG Pipeline safety

The DAG strategy implements Cycle Detection (Kahn's Algorithm). If the LLM proposes a circular dependency, the tool will intercept and report it as an error before wasting tokens.

@imguoguo @Zepan @afjcjsbx

Hi team! 👋

Just wanted to highlight that this PR (#976: feat: agent team) is directly building on and extending the foundational multi-agent work outlined in Issue #294 ("Feature: Base Multi-agent Collaboration Framework & Shared Context"), which is still marked as In Progress and is a key part of the Roadmap's Advanced Capabilities.

• Feature: Base Multi-agent Collaboration Framework & Shared Context #294 calls for transitioning to multi-agent architecture, shared context (blackboard), basic hand-off/delegation, agent lifecycle, and a standard Agent interface — all of which are prerequisites for more advanced orchestration.
• Earlier PRs like feat: Base multi-agent collaboration framework #409 and WIP: feat: base multi-agent collaboration framework & shared context #423 started the base (sub-agent spawning + shared context), but the actual team-level orchestration (sequential/parallel/DAG/evaluator-optimizer patterns) was left as the next logical step.

This PR implements exactly that missing layer:

• Full multi-agent team orchestration with 4 strategies (Sequential, Parallel, DAG, Evaluator-Optimizer)
• Concurrent goroutine execution for efficiency
• spawn_sub_agent tool + model-tag routing
• Shared context with configurable truncation/recovery
• Soft token budgets, partial success handling, reviewer_model for QA
• Structured logging, detailed docs, and recent fixes (goroutine leaks, dead code, etc. — latest push just now)

It stays compatible with the existing sub-agent foundation (#409/#423) while adding reliable coordination for complex decomposed tasks — precisely what #294 aims to enable as the base for community agents (Coder, Researcher, etc.), swarm mode, and beyond.

No conflicts, CI green, rebased on main.

Would really appreciate any initial feedback or eyes from the core team on:

• How well it aligns with Feature: Base Multi-agent Collaboration Framework & Shared Context #294's vision
• Architecture/strategy design choices
• Potential integration tweaks or simplifications

Super happy to iterate further (add tests, break into smaller PRs if needed, or discuss details). This feels like a natural progression to help close #294 and unlock the full multi-agent potential in PicoClaw! 🚀

Thanks for the incredible momentum (v0.2.2 release yesterday, constant merges) — excited to contribute to this growth.

Best regards,
@lppp04808

Hi,

Thank you for the thoughtful and focused proposal in #1439!
The emphasis on "What this does NOT propose" is especially helpful — it keeps the scope clearly on clarifying boundaries, fixing correctness issues (like orphaning, inaccurate estimation, reactive behavior), and shifting to proactive checks without introducing new abstractions or features.

While working on PR #976 (multi-agent team orchestration), I encountered several of the same context/token pain points in concurrent multi-agent scenarios and applied some patch-style fixes directly on the existing loop to improve reliability. These are not new mechanisms but simple adjustments that might help illustrate or validate the boundary clarifications and correctness improvements outlined in #1439.

Here are the relevant existing fixes in #976 that align with the proposal's goals:

• Soft token budget handling (proactive awareness instead of abrupt failure)
  Tracks remaining tokens per worker and team level, triggers a 50% advisory warning followed by a 0% wrap-up signal + final summary call to allow graceful completion rather than hard failure.
  Files: toolloop.go / team.go
  → This supports the shift from reactive to proactive budgeting and the history_budget concept for more predictable exhaustion behavior.

• Configurable injected context length limit (clearer truncation boundaries)
  Introduces max_context_runes (default 8000) to cap the length of context passed to downstream agents, preventing overflow in inter-agent communication.
  Files: team.go / context.go
  → Aligns with defining explicit truncation boundaries and avoiding unintended overflow as described.

• Truncation & finish_reason recovery (safe recovery from limits)
  Detects finish_reason=length or truncated responses and injects retry/fallback messages to prevent malformed outputs or broken loops.
  Files: provider.go (OpenAI compat) / toolloop.go
  → Complements the proactive pre-call check and safe recovery paths, helping ensure correctness after hitting limits.

• Preservation of critical context elements during truncation/budget hits
  Ensures thought_signature, session history, and chain-of-thought remain intact even when truncation or budget exhaustion occurs.
  Files: toolloop.go / context.go
  → Supports the tool-pair awareness goal (avoiding cuts in the middle of atomic groups) and maintains continuity without new structures.

• Partial success in Parallel execution
  Retains successful worker results even if others fail, allowing partial progress.
  → Indirectly aids in avoiding complete loss of valid context segments.

All of these are straightforward patches on the current agent loop (50 commits total, CI green, rebased on main), not new features. They were added to make multi-agent flows more robust in practice.

Once the boundary clarifications and correctness fixes from #1439 are applied in the refactor/agent branch, I'm happy to:

• rebase and adapt these adjustments to the updated context model
• contribute unit tests specifically targeting safe boundaries, non-orphaning tool pairs, accurate estimation, and proactive timing
• help validate that the proposed changes reduce wasted calls and improve correctness in multi-agent scenarios

If any of these existing patches can serve as a quick reference for testing the boundary definitions or proactive shifts (e.g., does the soft budget reduce abrupt failures? do the truncation rules prevent orphaning?), feel free to review them — I'd be glad to point to specific sections, share diffs, or assist in porting them.

Thanks again for driving this important track forward — excited to see the context foundation become more solid and predictable!
Any thoughts on priorities, potential conflicts with these patches, or next steps? Open to all feedback.

Closing this PR (#976) as we have now opened a clean v2 version:

New PR → feat(tools): restore and enhance team tool with SubTurn integratio

Reason for closing:

• Original feat: agent team #976 was built on the pre-Phase-1 architecture (direct RunToolLoop calls)

• v2 has been fully merged and significantly upgraded:

  • Full integration with SubTurnSpawner (isolated sessions, depth limit, concurrency semaphore, timeout, automatic truncation recovery)
  • ConcurrentFS + cross-member token budget tracking
  • Stateful iteration support for evaluator_optimizer strategy
  • Updated documentation and tests

• Perfectly aligns with the explicit task coordination part of Meta: Agent Refactor Phase 2 - Multi-Agent Collaboration within Single Pico #1934 Phase 2
  (Agent Discovery / implicit collaboration is deferred to a future PR)

This PR has served its purpose. v2 completely supersedes #976.

Thank you very much for the previous reviews on #976!
All future iterations will happen in the new PR. Looking forward to your feedback there~